=over

=item sysopen FILEHANDLE,FILENAME,MODE
X<sysopen>

=item sysopen FILEHANDLE,FILENAME,MODE,PERMS

Opens the file whose filename is given by FILENAME, and associates it with
FILEHANDLE.  If FILEHANDLE is an expression, its value is used as the real
filehandle wanted; an undefined scalar will be suitably autovivified.  This
function calls the underlying operating system's L<open(2)> function with the
parameters FILENAME, MODE, and PERMS.

Returns true on success and L<C<undef>|/undef EXPR> otherwise.

L<PerlIO> layers will be applied to the handle the same way they would in an
L<C<open>|/open FILEHANDLE,MODE,EXPR> call that does not specify layers. That is,
the current value of L<C<${^OPEN}>|perlvar/${^OPEN}> as set by the L<open>
pragma in a lexical scope, or the C<-C> commandline option or C<PERL_UNICODE>
environment variable in the main program scope, falling back to the platform
defaults as described in L<PerlIO/Defaults and how to override them>. If you
want to remove any layers that may transform the byte stream, use
L<C<binmode>|/binmode FILEHANDLE, LAYER> after opening it.

The possible values and flag bits of the MODE parameter are
system-dependent; they are available via the standard module
L<C<Fcntl>|Fcntl>.  See the documentation of your operating system's
L<open(2)> syscall to see
which values and flag bits are available.  You may combine several flags
using the C<|>-operator.

Some of the most common values are C<O_RDONLY> for opening the file in
read-only mode, C<O_WRONLY> for opening the file in write-only mode,
and C<O_RDWR> for opening the file in read-write mode.
X<O_RDONLY> X<O_RDWR> X<O_WRONLY>

For historical reasons, some values work on almost every system
supported by Perl: 0 means read-only, 1 means write-only, and 2
means read/write.  We know that these values do I<not> work under
OS/390 and on the Macintosh; you probably don't want to
use them in new code.

If the file named by FILENAME does not exist and the
L<C<open>|/open FILEHANDLE,MODE,EXPR> call creates
it (typically because MODE includes the C<O_CREAT> flag), then the value of
PERMS specifies the permissions of the newly created file.  If you omit
the PERMS argument to L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>,
Perl uses the octal value C<0666>.
These permission values need to be in octal, and are modified by your
process's current L<C<umask>|/umask EXPR>.
X<O_CREAT>

In many systems the C<O_EXCL> flag is available for opening files in
exclusive mode.  This is B<not> locking: exclusiveness means here that
if the file already exists,
L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> fails.  C<O_EXCL> may
not work
on network filesystems, and has no effect unless the C<O_CREAT> flag
is set as well.  Setting C<O_CREAT|O_EXCL> prevents the file from
being opened if it is a symbolic link.  It does not protect against
symbolic links in the file's path.
X<O_EXCL>

Sometimes you may want to truncate an already-existing file.  This
can be done using the C<O_TRUNC> flag.  The behavior of
C<O_TRUNC> with C<O_RDONLY> is undefined.
X<O_TRUNC>

You should seldom if ever use C<0644> as argument to
L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>, because
that takes away the user's option to have a more permissive umask.
Better to omit it.  See L<C<umask>|/umask EXPR> for more on this.

This function has no direct relation to the usage of
L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>,
L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>,
or L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>.  A handle opened with
this function can be used with buffered IO just as one opened with
L<C<open>|/open FILEHANDLE,MODE,EXPR> can be used with unbuffered IO.

Note that under Perls older than 5.8.0,
L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> depends on the
L<fdopen(3)> C library function.  On many Unix systems, L<fdopen(3)> is known
to fail when file descriptors exceed a certain value, typically 255.  If
you need more file descriptors than that, consider using the
L<C<POSIX::open>|POSIX/C<open>> function.  For Perls 5.8.0 and later,
PerlIO is (most often) the default.

See L<perlopentut> for a kinder, gentler explanation of opening files.

Portability issues: L<perlport/sysopen>.

=back